home *** CD-ROM | disk | FTP | other *** search
/ Universe of 3,000 Games / Universe of 3000 Game Patches.dmg / utils / jreader / jreadr25.doc < prev    next >
Text File  |  1995-03-27  |  21KB  |  446 lines
  1.  
  2.                            J R E A D E R
  3.  
  4.       Japanese Text Reader with Online Dictionary Search & Yomikata Lookup
  5.       ====================================================================
  6.  
  7.                             Version 2.5 
  8.  
  9.                                        
  10.                            (Copyright)
  11.                             J.W. Breen
  12.                            January 1995
  13.                                     
  14.  
  15.                              CONTENTS
  16.  
  17.                         1. INTRODUCTION
  18.  
  19.                         2. THIS DOCUMENT
  20.  
  21.                         3. INSTALLATION
  22.  
  23.                         4. ENVIRONMENT
  24.  
  25.                         5. OPERATION
  26.  
  27.                         6. DICTIONARY SEARCHING 
  28.  
  29.                         7. VERB & ADJECTIVE MODIFICATION
  30.  
  31.                         8. YOMIKATA SEARCHING
  32.  
  33.                         9. KANJI INFORMATION
  34.  
  35.                        10. JREADER ON A PALMTOP
  36.  
  37.                        11. ADDITIONS TO PREVIOUS VERSION(S)
  38.  
  39.                        12. AUTHOR'S COMMENT
  40.  
  41.  
  42.  
  43. 1. INTRODUCTION 
  44.  
  45. This program provides a PC operating under MS-DOS with the capability to read 
  46. and  display a text file containing Japanese characters (kana & kanji),  with 
  47. the option of looking up the displayed words in a Japanese/English dictionary 
  48. file or in a kanji-to-kana yomikata file.  
  49.  
  50. The Japanese characters in the text files can either be in the EUC,  New-JIS, 
  51. Old-JIS  or Shift-JIS codes.  Hankaku codes are supported for Shift-JIS,  but 
  52. not for EUC.  Codes which are not supported,  such as NEC-JIS or EUC-hankaku, 
  53. can be converted into one of the supported codes  using  a  utility  such  as 
  54. JCONV. 
  55.                  
  56. Although JREADER is  intended  to  help  non-Japanese  people  read  Japanese 
  57. language  text  files,  it can also be used by Japanese to read English text.  
  58. Its usefulness in this role is limited  by  the  dictionary,  which  is  more 
  59. oriented  to  the Japanese to English mode,  and the fact that the dictionary 
  60. search cannot cope with things like English's "strong" verbs (swim/swam/swum, 
  61. be/am/are, go/went, etc.). 
  62.  
  63. JREADER is an extension of the  author's  JDIC  (Japanese/English  Dictionary 
  64. Display)  program,  which  has  been  designed  specifically  to operate on a 
  65. dictionary in the "EDICT" format originally used  by  the  MOKE  (Mark's  Own 
  66. Kanji  Editor)  Japanese  text  editor.  As  with  JDIC,  JREADER's operating 
  67. environment has been designed to be similar to MOKE's,  and it  can  use  the 
  68. same  environment  variables  and control file as MOKE.  
  69.  
  70. The executable code and documentation of JREADER is hereby  released  to  the 
  71. public for general use.  It is covered by the author's copyright,  and may be 
  72. freely distributed with the proviso that it not be distributed as part  of  a 
  73. commercial system without the author's permission.  All usage of this program 
  74. is at the user's risk, and there is no warranty on its performance. 
  75.  
  76. All  the  Japanese  displayed is in kana and kanji,  so if you cannot read at 
  77. least hiragana and katakana,  this program will not be much use for you.  The 
  78. author has NO intention of producing a version using romanized Japanese. 
  79.  
  80.  
  81. 2. THIS DOCUMENT
  82.  
  83. JREADER  is  an  extension of JDIC,  and shares a similar operating method as 
  84. JDIC.  Consequently this document file only includes details of where JREADER 
  85. differs  from  JDIC.  Please  make  sure  you  have  and read the appropriate 
  86. JDICnn.doc file. 
  87.  
  88.  
  89. 3. INSTALLATION
  90.  
  91. This program is distributed in a "zoo" archive (jdic25.zoo).  Both  JDIC  and 
  92. JREADER share a common operating environment.  Please follow the installation 
  93. details in JDIC25.DOC, which is in the "JDIC25.ZOO" file. 
  94.  
  95. In addition, to get the full function from JREADER, you should have the files 
  96. WSKTOK.DAT  and  WSKTOK.IND.  These  are the kanji_to_kana file from MOKE and 
  97. its index file.  Without them the "y" (yomikata  lookup)  function  will  not 
  98. operate. If you are a MOKE user (Version 2.0 or later) you will have them. 
  99.  
  100. The author has produced an expanded form of the WSKTOK.DAT file by adding  in 
  101. the  additional entries in EDICT,  plus further entries from the full WNN and 
  102. SKK dictionaries.  This is available in the WSKWNN.ZOO  file,  along  with  a 
  103. matching WSKTOK.IND index file. 
  104.  
  105. (For the curious,  there is an explanation of these files in an  Appendix  to 
  106. JDIC25.DOC.) 
  107.  
  108.  
  109. 4. ENVIRONMENT
  110.  
  111. JREADER  uses  the  same  environment variables and JDIC.RC/MOKE.RC fields as 
  112. JDIC (and MOKE).  These affect things like paths and colours.  See JDIC25.DOC 
  113. for details. 
  114.  
  115. JREADER has one special (optional) entry in  the  JDIC.RC/MOKE.RC  file.  The 
  116. verb/adjective  deinflection  function  (see  below)  can  be disabled by the 
  117. following line in JDIC.RC/MOKE.RC: 
  118.  
  119. jverb   off
  120.  
  121. The default is for this option to be enabled.
  122.  
  123.  
  124. 5. OPERATION
  125.  
  126. (a) LOADING
  127.  
  128. JREADER is simple to operate. The command-line invocation is: 
  129.  
  130.          jreader <options> text-file(s)
  131.  
  132. The same -l,  -f,  -v,  -cDIR and -bnn  options  are  used  as  in  JDIC.  In 
  133. addition, JREADER uses: 
  134.  
  135.  -sn (3 < n < 8) specifies that the text window is to use n/10 of the screen, 
  136.                    The default is n = 7. 
  137.  
  138.  -ddictionary-file  specifies  the file that is to be used as the dictionary, 
  139.                    along with an index file  with  an  extension  of  ".jdx".  
  140.                    This latter file must be created using the JDXGEN utility.  
  141.                    The default is "edict" with "edict.jdx" as the index file, 
  142.                    or "jtoe.dct" and "jtoe.jdx", whichever is present. 
  143.                                        
  144.  -Llogfile  specifies the name of a file to log possible new "edict" entries. 
  145.                    The default name is "jreader.log". 
  146.  
  147.  -/search_string specifies a string for which a search is  invoked  when  the 
  148.                    file  is  read.  See  the  section  below on searching for 
  149.                    strings.  The same options are available as  in  a  string 
  150.                    entered from the keyboard, and as well a serach string can 
  151.                    be in (EUC coded) kanji or kana. 
  152.                    
  153. One or more file names can be provided. MS-DOS wildcards can be used also. 
  154.            
  155. (b) READING FILES
  156.  
  157. The working screen of JREADER contains two windows.  The upper  displays  the 
  158. text being read,  the lower displays control information,  and the dictionary 
  159. and yomikata search results. 
  160.  
  161. The lower window also displays a short "help" display when the window is  not 
  162. being  used for a regular display.  The help display can be turned off by the 
  163. "-v" command-line option and the "verbose off" line in the JDIC.RC  file.  It 
  164. can also be toggled on and off by the "o" command. 
  165.  
  166. The first screenful of the text file is displayed when  the  program  starts. 
  167. From then on most operation is by single keystroke commands. They are: 
  168.  
  169. <PgDn> reads the next screen of the file.  The  last  line  of  the  previous 
  170. screen is repeated as the first line of the next. 
  171.  
  172. <PgUp> reads the previous screen  of  the  file.  The  backspacing  technique 
  173. involves backspacing the number of lines on the current screen,  so it should 
  174. usually result in the previous screen being displayed,  unless  there  are  a 
  175. number of "folded" lines. 
  176.  
  177. <Ctrl-PgUp> restarts the file from the beginning. 
  178.           
  179. <Ctrl-PgDn> skips to the end of the file, and displays the last 10 lines. 
  180.  
  181. <Arrow>  The  four  arrow  keys  can  be  used to position the cursor under a 
  182. character which may be used as the start of a key for a dictionary search.  A 
  183. down-arrow while on the last line causes the display to scroll down one line, 
  184. and an up-arrow on the first line causes an upwards scroll. 
  185.  
  186. <Enter> positions the cursor at the start of the next line. 
  187.  
  188. <End> positions the cursor at the end of the current line. 
  189.  
  190. <Home> positions the cursor at the start of the current line. 
  191.  
  192. <Ctrl-Home> positions the cursor at the start of the screen. 
  193.  
  194. <Ctrl-End> positions the cursor at the last line of the screen. 
  195.  
  196. <Space> triggers a dictionary search using the string of characters beginning 
  197. with the one marked by the cursor. (See below.) 
  198.                                  
  199. <a> the same dictionary search as <space>,  but if the search key begins with 
  200. one or more kanji characters, the search will match against any occurrence of 
  201. the  character(s)  among  kanji compounds in the dictionary,  instead of just 
  202. those at the start of compounds. 
  203.  
  204. </> invokes a prompt for  a  string  of  characters,  the  file  is  searched 
  205. forwards, starting at the *second* line on the display, until a line is found 
  206. containing that string.  This scan is case sensitive. 
  207.  
  208. There are two special options with this search:
  209.  
  210.     (i) if the entered string begins with a "\",  the remainder is treated as 
  211.     a hexadecimal coding of one or more kanji or kana. If the first character 
  212.     of the code is a "k",  the coding is treated as Kuten-encoded,  and if it 
  213.     is an "s",  it  is  treated  as  Shift-JIS.  For  example,  \k3214  is  a 
  214.     Kuten-encoded kanji and \s82a4 is Shift-JIS encoded kana,  while \3b7a is 
  215.     a JIS encoded kanji. 
  216.     
  217.     (Note that it is possible to obtain an incorrect match on occasions  when 
  218.     using  this option,  particularly when searching for a single kanji.  The 
  219.     scan uses a simple "strstr" function,  which  is  not  sensitive  to  the 
  220.     boundaries of individual kanji or kana,  and thus may find a match on the 
  221.     the combination of the second byte of one character, and the first of the 
  222.     next.) 
  223.  
  224.     (ii) if the first character is a "?", the *previous* search is repeated.
  225.     
  226. Note that an initial search string can be entered as a  command-line  option. 
  227. In all cases the search can be abandoned by pressing the Esc key. 
  228.  
  229. <c> triggers a search similar to the "/" command,  except the  key  is  taken 
  230. from  the  screen,  starting  at  the cursor position.  You are asked for the 
  231. length of the key,  which may be up to 9  characters  long  (kana,  kanji  or 
  232. ASCII). You may repeat the search using the "/" command with the "?" option.
  233.  
  234. <l> logs the character string marked by the cursor  to  a  file  (default  is 
  235. "jreader.log").  The  logged  data is in "edict" format,  i.e.  `kanji [kana] 
  236. /english .../',  with the logged characters being  inserted  in  the  `kanji' 
  237. field.  You  will be prompted for the string length (up to 9 characters).  If 
  238. you respond with Enter,  and the cursor is on a Kanji,  all the kanji in  the 
  239. compound  will  be  logged.  You are also given the option of adding up to 50 
  240. characters of English to the logged entry.  (The main purpose of the  logging 
  241. function is to generate a file of Japanese words which are not  currently  in 
  242. the dictionary file.  This file can be edited later, the yomikata and English 
  243. translation  added  or  modified,  and  the  entries  included  in  the  full 
  244. dictionary.) 
  245.  
  246. <y> invokes a scan of the "WSKTOK.DAT" file to find the yomikata of the kanji 
  247. compound starting with the character at the cursor.  [This option only  works 
  248. if  the  "WSKTOK.DAT"  and  "WSKTOK.IND" files are available,  i.e.  you need 
  249. either to be a MOKE (2.0 or later) user,  or you need to  have  obtained  the 
  250. files  separately  from  the  "WSKWNN.ZOO"  archive.]  The  longest  matching 
  251. sequence is displayed,  and you are given the option of  logging  this  entry 
  252. (kanji and kana) to the "JREADER.LOG" file, along with up to 50 characters of 
  253. English.  In  combination  with the <l> option above,  this option provides a 
  254. useful way of building up the dictionary file. 
  255.                  
  256. <n>  looks up and displays various details about the character at the cursor. 
  257. If the character is kana or ASCII,  the JIS or hexadecimal code is displayed. 
  258. For  kanji,  the  information  displayed  is the JIS code in hex,  the Nelson 
  259. number, the Halpern number, the Radical number (Bushu), the stroke count, the 
  260. on and kun readings, the English meaning(s) and a number of other information 
  261. fields.  This function requires the "KINFO.DAT"  file  to  be  present.  (See 
  262. JDIC25.DOC and KANJIDIC.DOC for further information.) 
  263.  
  264. <s>  skips  ahead  in  the  text  file  to a line starting with "Article:" or 
  265. "Subject:".  This is to simplify reading a file containing  several  Japanese 
  266. news items. 
  267.  
  268. <k>  skips  the cursor to the start of the next Kanji compound.  If Automatic 
  269. Lookup mode is active,  the dictionary is searched for  this  compound.  (See 
  270. below)                                         
  271.  
  272. <w> skips the cursor to the start of the next of the next English word.  i.e. 
  273. the first slphabetic character after a non-alphabetic. 
  274.     
  275. <f>  initiates the opening of either the next file on the command line,  or a 
  276. totally new file. You are prompted for more details. 
  277.  
  278. <m> displays the next window of dictionary matches (if any). 
  279.  
  280. <d>  displays  a status report of the files in use,  the position in the file 
  281. being read,  the buffer usage,  and the state of user configurable  switches. 
  282. Note  that  the  line position is not always accurate if there have been some 
  283. PgUps,  and particularly if the Ctrl-PgDn skip_to_EOF option has  been  used, 
  284. which case the line count is set to 9999. 
  285.  
  286. <j> jump ahead a number of lines. There is a prompt asking for the number. 
  287.  
  288. <v> toggles the verb deinflection function between enabled and disabled. 
  289.  
  290. <b> toggles the automatic blanking of the lower window.  Normally the display 
  291. on the lower window is left there until the next search, log, etc. is carried 
  292. out.  Some users prefer not to have such displays present.  The  <b>  command 
  293. toggles on and off a function which  will  blank  the  lower  window  on  any 
  294. keystroke following a search. 
  295.  
  296. <o>  toggles  the  production of the help display in the lower window.  (When 
  297. this option is in use,  it over-rides the operation of the automatic blanking 
  298. of the lower window.) 
  299.  
  300. <F1> Displays a summary of the keyboard commands. 
  301.  
  302. <F2> Toggles Automatic Lookup mode (See <k> above.) 
  303.  
  304.  
  305. 6. DICTIONARY SEARCHING 
  306.  
  307. The dictionary search is similar to the one used in JDIC, except that the key 
  308. is  taken  from  the  text being displayed,  rather than from keyboard input.  
  309. Thus the search can be on keys consisting of kanji compounds, as well as kana 
  310. and ascii. 
  311.  
  312. Starting with the character marked by the cursor,  the longest match is found 
  313. and  displayed,  followed by the next longest,  and so on.  Usually the first 
  314. match is the one you want.  The dictionary display is identical  to  that  in 
  315. JDIC,  except that each line is preceded by the number of matched characters.  
  316. If there are more matched lines than fit in the window, pressing "m" displays 
  317. the next window-full. 
  318.  
  319.  
  320. 7. VERB & ADJECTIVE MODIFICATION
  321.  
  322. When  a  dictionary  search  is initiated for text which consists of a single 
  323. kanji followed by two or more kana,  JREADER checks to see if it one  of  the 
  324. common verb or adjective conjugations or inflections, and if so, examines the 
  325. dictionary  using  the derived "plain" or "dictionary form" of the word.  The 
  326. user may then proceed with a normal search.  The inflection details used  are 
  327. in  the  file  "VCONJ",  which  may  be modified by the user.  Note that this 
  328. feature can be disabled by setting "jverb off" in the  JDIC.RC/MOKE.RC  file, 
  329. or  by  omitting the VCONJ file.  It can also be turned on or off dynamically 
  330. with the "v" command. 
  331.  
  332. This function is not highly sophisticated,  and will not always  produce  the 
  333. right  result,  particularly when handling the more obscure grammatical forms 
  334. which use the "-masu stem" of verbs.  It is correct, however, over 95% of the 
  335. time,  and eliminates the problem of having the dictionary entry matching the 
  336. selected text only appearing about 20 or 30 lines down the display. 
  337.  
  338.  
  339. 8. YOMIKATA SEARCHING
  340.  
  341. The  "WSKTOK.DAT"  file  contains  thousands  of  kanji  compounds with their 
  342. readings in kana.  It is sorted,  and indexed on the first byte of the  first 
  343. character  in  the "WSKTOK.IND" file.  JREADER seeks into and scans this file 
  344. for the longest matching sequence of characters.  Only one such  compound  is 
  345. displayed.  The  present author has expanded the original MOKE file,  and the 
  346. expanded version is available in the WSKWNN.ZOO archive. 
  347.  
  348.  
  349. 9. KANJI INFORMATION
  350.  
  351. The  kanji  information  displayed  by  the  <n>  command  is  in  the   file 
  352. "KINFO.DAT".   KINFO.DAT  is  built  from  the  "KANJIDIC"  file.   See   the 
  353. KANJIDIC.DOC file for the full details on this information,  and the Appendix 
  354. to JDIC25.DOC for the structure of KINFO.DAT. 
  355.   
  356.  
  357. 10. JREADER ON A PALMTOP
  358.   
  359. JREADER  can  be  used successfully on the tiny HP100LX Palmtop (and probably 
  360. other emerging PCs of this type.) See JDIC25.DOC for more  details  of  this. 
  361. The author operates JREADER on a Palmtop by: 
  362.  
  363. (a) installing it in the Application Manager as a call to a batch file,  i.e. 
  364. the "Path" box contains:  "a:\kanji\jrbat.bat|350".  Note that the "|" is the 
  365. upside-down "!". 
  366.  
  367. (b) creating a batch file (JRBAT.BAT) containing the following lines: 
  368.  
  369.         @echo off
  370.         input File Name(s) for JREADER? :
  371.         jreader -f -s6 %ANS%
  372.         
  373. The  "input.com"  utility,  which  is  in  the JDICPALM.ZOO archive,  is a PD 
  374. program which enables a text string (e.g.  a  file  name)  to  be  passed  to 
  375. JREADER via the "ANS" environment variable. 
  376.  
  377. 11. ADDITIONS TO PREVIOUS VERSION(S)
  378.  
  379. V1.1 - Yomikata lookup, TAB expansion,  Shift-JIS reading,  PgUp for previous 
  380. screen. 
  381.  
  382. V2.0  -  Larger  Help Screen,  double-Escape to exit,  "n" command to look up 
  383. Nelson,  etc.  information,  alternative font  files  and  dictionary  names, 
  384. multiple  input  files,  file  restart,  single-line scrolling,  text search, 
  385. paging of font and index files, capability of handling a dictionary up to 1.5 
  386. Mbytes. 
  387.  
  388. V2.1 - Adds the ability to match a kanji with any occurrence  of  it  in  the 
  389. dictionary (the <a> function). 
  390.  
  391. V2.2  -  Removes  the 1.5Mbyte restriction on dictionary size.  Tidies up the 
  392. kanji display (<n> option). 
  393.  
  394. V2.3 - Added  the  verb/adjective  deinflector  facility,  the  <j>  and  <d> 
  395. options,  the  Kuten  field in the kanji display.  Enabled the display of the 
  396. last 4 JIS2 kanji when using the K16JIS2.FNT file.  Added the  JDIC.RC  file.  
  397. The   -cDIR  command-line  option.   Improved  the  search  speed,   and  the 
  398. line-folding in the dictionary and kanji display. 
  399.  
  400. V2.4  -  compressed  the display,  including introducing user-selectable font 
  401. spacing,  and rearranging the lower window to enable better operation on  CGA 
  402. displays  (e.g.  the HP Palmtop.) Added the <b> blanking of the lower screen, 
  403. and the "Searching ..." message.  Added the handling of  half-width  kana  in 
  404. SJIS  files.  For  text searching,  added the <c> option,  the "\" setting of 
  405. JIS, SJIS and Kuten,  the command-line option,  and the "?" repeat.  Expanded 
  406. the "d" display, and fixed the erroneous line counts.  Added the help display 
  407. in the lower window.                        
  408.  
  409. V2.5 - the EDICT Extension file facility <e>.
  410.  
  411.  
  412. 12. AUTHOR'S COMMENT
  413.  
  414. JREADER is to me a natural extension of JDIC,  and further exploits the  fast 
  415. dictionary  scanning technique used therein.  It also has been written with a 
  416. need in mind.  I had been using Mark Edwards' excellent VIEW and MOKE to read 
  417. fj.* news (using the SNUZ news reader.) I was frustrated by the  slowness  of 
  418. the  English  lookup  in  MOKE (a sequential read of the entire file) and its 
  419. refusal to add a compound to the dictionary if it was not in  the  kanji/kana 
  420. henkan  file.  Also  both  MOKE  and  VIEW require precise delineation of the 
  421. search string using several keystrokes.  This  can  result  in  several  slow 
  422. attempts  to  find  meanings for portions of a kanji compound.  What I wanted 
  423. was something friendlier and  faster  in  a  reading  environment,  with  the 
  424. capability of providing updates to my EDICT dictionary. 
  425.  
  426. From this grew JREADER,  and it has turned out to be a very powerful Japanese 
  427. text  reader,  with  many  devoted  users  around the world.  (JREADER's code 
  428. actually formed the basis of the code for XJDIC,  the Unix X11 port of  JDIC, 
  429. because  XJDIC  provides virtually all of JREADER's functionality through the 
  430. kterm cut_and_paste facility.) To my delight,  the compilers  of  the  Walnut 
  431. Creek "East Asian Text Processing" CDROM  sought  my  permission  to  include 
  432. JREADER as the default Japanese text reader. 
  433.  
  434. As  with  the JDIC program,  I am grateful to the many beta-testers,  and the 
  435. people who have suggested operational improvements, many of which I have been 
  436. able to incorporate. 
  437.  
  438. As ever, comments and suggestions are welcome. 
  439.  
  440. Jim Breen (jwb@capek.rdt.monash.edu.au) 
  441. Department of Robotics & Digital Technology 
  442. Monash University 
  443. Melbourne, Australia                                    
  444. Nov 1991 - March 1995
  445.  
  446.